home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / CUGUK / COMMS / C035.ZIP / OLD_JMOD / JMODEM.DOC < prev    next >
Text File  |  1990-01-20  |  36KB  |  1,063 lines
  1.  
  2.                                   J M O D E M
  3.                               File Transfer System
  4.                                  Compliments of
  5.                                Richard B. Johnson
  6.                                 PROGRAM EXCHANGE
  7.                                  (508) 922-3166
  8.                                 January 20, 1990
  9.  
  10.           General:
  11.           First Let me get this over with.
  12.           MS-DOS is a registered trademark of Microsoft Corporation
  13.           IBM, IBM-PC, IBM-XT, AT, are registered trademarks of
  14.           International Business Machines, Inc. WILDCAT! is a trade-
  15.           mark of Mustang Software. XMODEM is a public-domain file-
  16.           transfer protocol developed by Ward Christensen.
  17.  
  18.           JMODEM is released into the public domain. As with most
  19.           public-domain protocols, you are advised that there is no
  20.           implied warranty of any kind. The source-code is provided so
  21.           that you may determine for yourself if this program may
  22.           serve a useful purpose. It is written in Microsoft MASM
  23.           Assembly-language using good standards of engineering
  24.           practice. It does not use any strange or "undocumented"
  25.           functions of the MS-DOS operating system.
  26.  
  27.                 PLEASE UPLOAD THIS FILE (The ARC file) to as many
  28.                 BBS systems as you can so that it gets installed
  29.                 all around the country.
  30.  
  31.           Introduction:
  32.           JMODEM is a new file-transfer protocol developed to be used
  33.           as an "external protocol" on BBS systems and personal com-
  34.           puters using the IBM-PC/AT/XT structure and the MS-DOS oper-
  35.           ating system.
  36.  
  37.           This file-transfer system features:
  38.  
  39.                 o       16-bit CRC for verification
  40.                 o       File size is exactly maintained
  41.                 o       Data compression.
  42.                 o       Rapid host/remote synchronization.
  43.                 o       Variable-length transmission blocks which,
  44.                         if there are few errors, increase to 8192
  45.                         data-bytes in length.
  46.                 o       Flow control (automatic)
  47.                 o       Hangup protection
  48.                 o       Aborted files are saved
  49.                 o       Files being overwritten are renamed to
  50.                         ".OLD", rather than deleted.
  51.                 o       COM1 - COM4 support.
  52.                 o       Interrupt on received characters allows data
  53.                         to be received while the previous block is
  54.                         being written to disk. This provides almost
  55.  
  56.  
  57.  
  58.  
  59.                                      - 1 -
  60.                                                JMODEM Protocol  Page 2
  61.  
  62.                         continuous data transmission without long
  63.                         waits between blocks.
  64.  
  65.           JMODEM is not for everyone! It does not have any pretty
  66.           screens to dazzle the user. It is designed to maximize the
  67.           amount of data that can be transferred in a given time (and
  68.           reduce telephone cost). It does this by sending very long
  69.           blocks of data and encoding (compressing) the data wherever
  70.           possible. Since long blocks of data are subject to many
  71.           transmission errors, a 16 bit CRC is used to determine the
  72.           data integrity. As many as ten retries are made if the data
  73.           is not correctly received. If you have a noisy telephone
  74.           circuit, you will find that JMODEM will abort more often
  75.           than the XMODEM protocol which sends very short blocks. A
  76.           future version that will be downward-compatible with the
  77.           existing version is being developed that will do "heroic"
  78.           retries and will even go down to a 16-byte block-lengths if
  79.           that's what is necessary to get the data transferred.
  80.  
  81.           Once synchronization between the remote computer and the
  82.           host are established, JMODEM paints a status block on the
  83.           screen that shows how the file transfer is going. The status
  84.           screen shows the block being transmitted (or the last re-
  85.           ceived), the length of the block, and the total bytes having
  86.           been transmitted (or received). A special synchronization
  87.           routine is used so that the first block is not thrown away
  88.           as happens so often in XMODEM type routines. During the
  89.           synchronization routine, where the host is waiting for the
  90.           user to enter the proper file parameters (a 30 second wait).
  91.           You can abort immediately by sending a control X (^X). After
  92.           actual file transfer begins, ie. when you see the status
  93.           window on the screen, no input from the keyboard is pos-
  94.           sible. You send a control BREAK to abort the transmission
  95.           (or ^C). In this case, the program will abort after the
  96.           block being sent/received is complete. This could take 15 or
  97.           more seconds with long blocks so be patient.
  98.  
  99.           In the event that carrier is lost (the user disconnected),
  100.           the file-transfer program will also abort. This, too, could
  101.           take as long as 15 seconds. JMODEM has logic to determine if
  102.           the modem carrier was present when it started. This will
  103.           allow you to transfer files between computers with a wire
  104.           without having to tie the RLSD lead high.
  105.  
  106.           How it works:
  107.           The block size starts out at 512 bytes (or the actual bytes
  108.           in the file -- whichever is less). To this is added a 6-byte
  109.           overhead. If the block transfer occurred without any re-
  110.           tries, the block length is increased by 512 bytes to 1024
  111.           bytes. As long as the transmission was successful without
  112.           incurring any re-tries, the block-length increases to a max-
  113.           imum of 8192 bytes. There is still the same 6-byte overhead
  114.  
  115.  
  116.  
  117.  
  118.                                      - 2 -
  119.                                                JMODEM Protocol  Page 3
  120.  
  121.           so the maximum block length will actually be 8198 bytes. Any
  122.           time there are retries, the block length (on the next new
  123.           string) is decreased by 512 bytes. The string-length is
  124.           never reduced to less than 512 bytes due to errors. When the
  125.           last bytes are read from the file, the block length may be
  126.           as little as 7 bytes (one data byte, plus the 6 byte over-
  127.           head). The file size as received will be exactly the file
  128.           size as transmitted. XMODEM will "round-up" the file size to
  129.           the next higher block. This means that MS-DOS's COMP (com-
  130.           pare) will always fail when you attempt to check files that
  131.           have been sent by XMODEM and many other protocols.
  132.  
  133.           When the file is read, an attempt is made to compress the
  134.           data using the well-known RLL process where multiple bytes
  135.           are compressed into a 4-byte statement.
  136.  
  137.           For instance a string that looks like this (hex):
  138.                 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0
  139.           Gets compressed into this:
  140.                 BB 0F 00 A0
  141.                  |  |  |  |__________ Byte to repeat
  142.                  |  |  |_____________ High byte of repeat length
  143.                  |  |________________ Low byte of repeat length
  144.                  |___________________ Sentinel Byte
  145.  
  146.           The sentinel-byte (BBH), when encountered in a data stream
  147.           will get expanded to four bytes. Therefore, it is possible
  148.           for the "compressed" data string to actually be longer than
  149.           the original. If this occurs, the original string is sent
  150.           rather than the longer encoded one. Since the kind of data
  151.           sent can be different from block-to-block, it is necessary
  152.           to send a control-byte along with the data so the receiver
  153.           had determine how to operate on the data.
  154.  
  155.           This is the control structure:
  156.  
  157.           00 02 00 0B 01 02 03 04 05 06 07 08 09 0A .... 0A EA
  158.            |  |  |  |  |                                 |  |_ CRC
  159.            |  |  |  |  |                                 |____ CRC
  160.            |  |  |  |  |______________________________________ data
  161.            |  |  |  |_________________________________________ rec.
  162.            |  |  |____________________________________________ control
  163.            |  |_______________________________________________ length
  164.            |__________________________________________________ Length
  165.  
  166.           Two bytes are used for the string length and two bytes are
  167.           used for the CRC. As is standard in memory, the high-byte
  168.           looks "to people using DEBUG" swapped with the low byte. The
  169.           data is transmitted exactly as the memory image.
  170.  
  171.           The length (a word) begins the string so the receiver may
  172.           know exactly how may bytes to receive.
  173.  
  174.  
  175.  
  176.  
  177.                                      - 3 -
  178.                                                JMODEM Protocol  Page 4
  179.  
  180.  
  181.           The control byte is bit-mapped to 8 possibilities. The ones
  182.           most important are:
  183.  
  184.                         NORMAL DATA
  185.                         COMPRESSED DATA
  186.                         END OF FILE
  187.                         ABORT
  188.  
  189.           This is now the receiver "knows" what to do with the data.
  190.  
  191.           The CRC is generated using this polynomial:
  192.  
  193.           X =  X + X^(2(n-mod 7)).......  Where n = t(n-1)
  194.                                          And t = string length
  195.  
  196.           It has the advantage of simplicity in assembly-language
  197.           programming and will detect errors with a probability of
  198.           about  one undetected error in 2^132 (which is a very large
  199.           number). It does not correct errors so its not important to
  200.           use some "standard" function to generate the CRC.
  201.  
  202.           Support for COM3 and COM4 have been added on revision level
  203.           V1.05 . Note that the standards for port locations are de-
  204.           facto standards only and may not be the ports actually used
  205.           in your computer. Please modify the communications port
  206.           structures at the beginning of the assembly-language program
  207.           to match your system parameters if they are different. The
  208.           modifications should be done to the STRUCTURES, not to the
  209.           EQUATES!
  210.  
  211.           Revision level V1.09 brings musical exit status. If the file
  212.           transfer was successful, the computer plays "victory". If
  213.           the file transfer was aborted, the computer plays "retreat".
  214.           Since the BBS SysOp is unlikely to want his computer to play
  215.           bugle-calls well into the evening, the user has the option
  216.           of turning the music off. This is done by setting an en-
  217.           vironment variable string:
  218.  
  219.           SET JMODEM=SHUTUP
  220.  
  221.                 ... Will accomplish the desired result.
  222.           Usage:
  223.           This program uses parameters on the command line.
  224.  
  225.           JMODEM S <filename.typ>       ( Sends a file to COM1:)
  226.           JMODEM R <filename.typ>       ( Receives a file from COM1:)
  227.           JMODEM S1 <filename.typ>      ( Sends a file to COM1:)
  228.           JMODEM R1 <filename.typ>      ( Receives a file from COM1:)
  229.           JMODEM S2 <filename.typ>      ( Sends a file to COM2:)
  230.           JMODEM R2 <filename.typ>      ( Receives a file from COM2:)
  231.  
  232.  
  233.  
  234.  
  235.  
  236.                                      - 4 -
  237.                                                JMODEM Protocol  Page 5
  238.  
  239.           After version 1.05, JMODEM supported communications adapter
  240.           ports 1 through 4.
  241.  
  242.           In a batch file, <filename.typ> may be a substitution
  243.           character.
  244.           JMODEM S2 %1                  ( Sends a file to COM2:)
  245.           JMODEM R2 %1                  ( Receives a file from COM2:)
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.                                      - 5 -
  296.                                                JMODEM Protocol  Page 6
  297.  
  298.                       Setting up a Communications Program
  299.                         External File-Transfer Protocol.
  300.  
  301.           On my system, TELIX resides in the C:\TELIX directory. A
  302.           copy of JMODEM.COM is also in that directory. TELIX passes
  303.           the filename as the %3 parameter. Therefore the contents of
  304.           JUP.BAT is:
  305.  
  306.                         C:\TELIX\JMODEM S1 %3
  307.  
  308.           The contents of JDOWN.BAT are:
  309.  
  310.                         C:\TELIX\JMODEM R1 %3
  311.  
  312.           If I wished to receive in the "batch" mode, I could make a
  313.           file like this. Notice that some communications programs do
  314.           not allow multiple file names. Note that the comments "!"
  315.           are NOT ALLOWED in a DOS batch file.
  316.  
  317.                         :DO_LOOP                   ! Return here
  318.                         IF "%3" == "" GOTO DONE    ! More parameters?
  319.                         C:\TELIX\JMODEM R1 %3      ! Execute JMODEM
  320.                         IF ERRORLEVEL 1 GOTO DONE  ! Abort on error
  321.                         SHIFT                      ! %4 becomes %3
  322.                         GOTO DO_LOOP               ! Continue
  323.                         :DONE                      ! Exit batch file
  324.  
  325.           If you do not know what "%" parameters are used to pass the
  326.           file name, all you have to do is make a "dummy" batch file
  327.           that contains the following:
  328.  
  329.                         @ECHO OFF
  330.                         ECHO %1
  331.                         ECHO %2
  332.                         ECHO %3
  333.                         ECHO %4
  334.                         ECHO %5
  335.                         PAUSE
  336.  
  337.           When this is executed, you will see something like this:
  338.  
  339.                 1200
  340.                 1
  341.                 FILENAME.TYP
  342.                 ECHO is off
  343.                 ECHO is off
  344.                 Strike a key when ready . . .
  345.  
  346.           The first line contains "1200" which is the baud rate. This
  347.           means that the %1 parameter contains the baud rate.
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.                                      - 6 -
  355.                                                JMODEM Protocol  Page 7
  356.  
  357.           The second line contains "1" which is the communications
  358.           adapter port being used. This means that the port is being
  359.           passed as the %2 parameter.
  360.  
  361.           The third line contains "FILENAME.TYP" which is the file
  362.           name. This means that the file name is being passed as the
  363.           %3 parameter.
  364.  
  365.           The fourth and fifth lines contain nothing to echo so DOS
  366.           replies the current state of the echo function which is
  367.           "off".
  368.  
  369.           PCPLUS handles the file name passing a little bit different.
  370.           If I execute the same "dummy" batch file from the PCPLUS
  371.           directory, the response is:
  372.  
  373.                 FILENAME.TYP
  374.                 ECHO is off
  375.                 ECHO is off
  376.                 ECHO is off
  377.                 ECHO is off
  378.                 Strike a key when ready . . .
  379.  
  380.           This shows us that PCPLUS passes the file name as the first
  381.           parameter and there are no other parameters. However, If I
  382.           put more parameters on the command line within PCPLUS, they
  383.           will get sent to the batch file. The response is:
  384.  
  385.                 FILENAME.001
  386.                 FILENAME.002
  387.                 FILENAME.003
  388.                 FILENAME.
  389.                 ECHO is off
  390.                 Strike a key when ready . . .
  391.  
  392.           Therefore PCPLUS allows up to four file names to be passed
  393.           providing there's room on the command line.
  394.  
  395.           Notice that these two communications programs check the
  396.           default directory for the external protocol batch file
  397.           FIRST! Therefore you must make certain that there are no
  398.           other similarly-named batch files in the current directory
  399.           or within the current path. Failure to do so will cause the
  400.           improper execution of the wrong batch file. Lets say that
  401.           the path was "C:\DOS;C:\TOOLS;C:\PCPLUS;C:\TELIX;C:\QMODEM".
  402.           If you named all your JMODEM external protocol batch files
  403.           with the same name, and you were attempting to use an ex-
  404.           ternal file transfer protocol from QMODEM, the batch file
  405.           designed to operate with PCPLUS would be the first one
  406.           "found" and executed since the search-path will search the
  407.           \PCPLUS directory before the \QMODEM directory. You prevent
  408.           the execution of the incorrect batch file by calling them
  409.           slightly different names.
  410.  
  411.  
  412.  
  413.                                      - 7 -
  414.                                                JMODEM Protocol  Page 8
  415.  
  416.  
  417.           When setting up external protocols, remember to configure
  418.           the communications program so that it prompts you for the
  419.           file names. Unlike some protocols, JMODEM does not transfer
  420.           the file name. You can use any file name that you wish. You
  421.           must pass the file name to JMODEM since it must know the
  422.           name of the file being transmitted or received. There are no
  423.           defaults.
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.                                      - 8 -
  473.                                                JMODEM Protocol  Page 9
  474.  
  475.                             Setting up a BBS System
  476.                         External File-Transfer Protocol.
  477.  
  478.  
  479.           If you are running a WILDCAT! bulletin board, the external
  480.           protocol files can be set up like this:
  481.  
  482.                         (JUP.BAT)
  483.                         CD D:\WILDCAT\PROTOCOL
  484.                         IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  485.                         JMODEM R1 %3
  486.                         IF ERRORLEVEL 1 GOTO END
  487.                         COPY %3 %4
  488.                         :END
  489.                         DEL %3
  490.  
  491.                         (JDOWN.BAT)
  492.                         CD D:\WILDCAT\PROTOCOL
  493.                         IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  494.                         JMODEM S1 %3
  495.                         IF ERRORLEVEL 1 GOTO BAD
  496.                         GOTO END
  497.                         :BAD
  498.                         COPY ALL.OK TRANSFER.BAD
  499.                         :END
  500.  
  501.           There are many variations available. Since WILDCAT! supports
  502.           batch-mode downloading, you could set up the batch file like
  503.           this:
  504.  
  505.                         (JDOWN.BAT)
  506.                         CD D:\WILDCAT\PROTOCOL
  507.                         IF EXIST TRANSFER.BAD DEL TRANSFER.BAD
  508.                         :DO_LOOP
  509.                         IF "%3" == "" GOTO END
  510.                         JMODEM S1 %3
  511.                         IF ERRORLEVEL 1 GOTO BAD
  512.                         SHIFT
  513.                         GOTO DO_LOOP
  514.                         :BAD
  515.                         COPY ALL.OK TRANSFER.BAD
  516.                         :END
  517.  
  518.           WILDCAT! checks the \PROTOCOL directory to see if the file
  519.           TRANSFER.BAD has been created. If it exists, it announces
  520.           that the file transfer has failed. It also announces "Error
  521.           with external protocol .. ". It does this when, in fact,
  522.           WILDCAT!  has made an error itself. In many cases WILDCAT!
  523.           will "find" the file TRANSFER.BAD when it DOES NOT EXIST! In
  524.           spite of this bug, WILDCAT! is one of the most reliable BBS
  525.           systems supporting external protocols.
  526.  
  527.  
  528.  
  529.  
  530.  
  531.                                      - 9 -
  532.                                               JMODEM Protocol  Page 10
  533.  
  534.           When setting up batch files remember that there is also a
  535.           bug in all DOS versions. The "IF ERRORLEVEL " statement does
  536.           NOT test the actual value of ERRORLEVEL! Instead it checks
  537.           to see if the returned value is EQUAL or GREATER than the
  538.           tested value. If you were to put the statement:
  539.  
  540.                         IF ERRORLEVEL 0 GOTO GOOD
  541.  
  542.           .... in a batch file, the execution would ALWAYS branch to
  543.           label "GOOD" regardless of the actual ERRORLEVEL returned!
  544.           More about bugs when we get to the "BAD BBS" section towards
  545.           the end.
  546.  
  547.           JMODEM does not require any information about handshaking.
  548.           It will look at the modem port and figure out for itself
  549.           what to do.
  550.  
  551.           In the event that the modem carrier is lost, JMODEM will
  552.           abort. Since JMODEM only checks the modem port occasionally,
  553.           it may take several seconds to abort when the carrier is
  554.           lost. It is impossible for a user to get at the DOS level
  555.           through JMODEM. Do NOT use the CTTY command in the external
  556.           protocol batch files. JMODEM returns ERRORLEVEL 1 if there
  557.           was any error in transmission or reception. It returns
  558.           ERRORLEVEL 0 (no error) otherwise. It does not delete files
  559.           that have been partially received although it properly clos-
  560.           es them. The system operator can arrange the batch files to
  561.           delete them if required.
  562.  
  563.           When JMODEM attempts to create a file that already exists it
  564.           can't ask the user if the old one should be deleted since
  565.           the user is probably not in a terminal program at the time.
  566.           Therefore, JMODEM renames the other file to <filename.OLD>
  567.           and creates the new file. In the event that <filaname.OLD>
  568.           exists, it is deleted before the rename operation occurs.
  569.  
  570.           If you don't know what parameters are being sent to external
  571.           protocols, you can make a dummy batch file to check them
  572.           using the DOS's echo command just as explained in the user
  573.           interface previous to this "BBS" section. You can't see the
  574.           parameters being echoed from a remote terminal. You must be
  575.           present at the BBS board terminal to test those parameters
  576.           unless you modify the dummy command file like this:
  577.  
  578.                         @ECHO OFF
  579.                         ECHO %1>COM1
  580.                         ECHO %2>COM1
  581.                         ECHO %3>COM1
  582.                         ECHO %4>COM1
  583.                         ECHO %5>COM1
  584.  
  585.           If you find that your system passes the file name as %3,
  586.           your "upload" (receive) batch file would contain this:
  587.  
  588.  
  589.  
  590.                                      - 10 -
  591.                                               JMODEM Protocol  Page 11
  592.  
  593.  
  594.                         JMODEM R1 %3
  595.  
  596.           Your "download" (send) batch file would contain this:
  597.  
  598.                         JMODEM S1 %3
  599.  
  600.           In these examples, it is assumed that you are using
  601.           communications adapter port "1".
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.                                      - 11 -
  650.                                               JMODEM Protocol  Page 12
  651.  
  652.                                   The BAD BBS
  653.                                     Problem.
  654.  
  655.           Believe it or not, there are several very fine running BBS
  656.           systems in use that do not properly handle external proto-
  657.           cols. MS-DOS provides the proper mechanism for loading and
  658.           executing "child" programs from within the "parent" pro-
  659.           grams. This is function 4BH of the "DOS" INT 21H DOS inter-
  660.           face. Instead of using this function, these poorly-behaved
  661.           programs perform the external file-transfer protocol in the
  662.           following (or similar) manner:
  663.  
  664.                 (1) Make a DOS call to find the file-size of the
  665.           external file-transfer protocol.
  666.  
  667.                 (2) Free up an array of memory from "string-space"
  668.           within the program that is large enough to copy the external
  669.           file transfer contents into it. As assumption about the
  670.           data-space required by the external file transfer program is
  671.           made based upon the "block-size" information that has been
  672.           entered during configuration.
  673.  
  674.                 (3) Loads the file into string-space memory.
  675.  
  676.                 (4) If its an ".EXE" file, ignore the header.
  677.  
  678.                 (5) CALL the first byte of code!
  679.  
  680.                 If JMODEM is run in this environment, it WILL crash
  681.           the system. JMODEM assumes that it has been placed in memory
  682.           by MS-DOS and that an entire segment (64k) is available to
  683.           run. JMODEM uses two buffers that are almost 32k in length!
  684.           One of the buffers is used to support data compression and
  685.           expansion. The other is used for the interrupt buffer.
  686.  
  687.           If you have such a BBS system and you wish to run JMODEM,
  688.           you can make a simple modification to the source-code, and
  689.           re-compile to produce a version which is a bit slower to
  690.           initialize and exit, but is guaranteed to leave all memory
  691.           and registers EXACTLY as they were when JMODEM got control.
  692.           This is done by saving and restoring all registers. Ad-
  693.           ditionally, any data space that will be modified is copied
  694.           to a file called VIRTUAL.MEM, then restored from that file
  695.           just before JMODEM exits.
  696.  
  697.           You modify the source-code by finding the "BAD_BBS" equate
  698.           near the beginning of the file. This is normally set to
  699.           "FALSE". You set this to "TRUE". Then you recompile in the
  700.           following manner:
  701.  
  702.                 MASM JMODEM;
  703.                 LINK JMODEM;
  704.  
  705.  
  706.  
  707.  
  708.                                      - 12 -
  709.                                               JMODEM Protocol  Page 13
  710.  
  711.                 EXE2BIN JMODEM.EXE JMODEM.COM
  712.                 DEL JMODEM.EXE
  713.  
  714.           Do NOT attempt to execute the ".EXE" version. You must
  715.           change JMODEM to a ".COM" file. If you do not have
  716.           EXE2BIN.COM to make the change, you can use DOS's DEBUG to
  717.           do the same thing. You do it this way:
  718.  
  719.           F:\DEV> debug jmodem.exe      ; DOS command line
  720.           -rcx                          ; Examine CX register
  721.           CX 1239                       ; Debug says the size was 1239
  722.           :
  723.  
  724.           -h 1239,100                   ; Calculate 1239H - 100H
  725.           1339  1139                    ; Sum = 1339H, dif = 1139H
  726.           -rcx                          ; Examine register again
  727.           CX 1239                       ; Is 1239H
  728.           :1139                         ; Change to 1139H
  729.                                         ; .. subtract 100H
  730.           -njmodem.com                  ; Name new SAVE file name
  731.           -w                            ; Write to file
  732.  
  733.           Writing 1139 bytes            ; Debug prompts
  734.           -q                            ; Exit
  735.  
  736.           F:\DEV>                       ; Back to DOS
  737.  
  738.           When you use this version of JMODEM, it will take a little
  739.           while longer to load and exit because it must write a 64k
  740.           block of memory to a file and read / delete in upon exit.
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.                                      - 13 -
  768.                                               JMODEM Protocol  Page 14
  769.  
  770.                             When things don't work!
  771.  
  772.           The early versions of JMODEM assumed that it was being
  773.           properly loaded either by COMMAND.COM, the resident command
  774.           processor, or by a "parent" process that properly executes
  775.           the DOS function 1BH (the EXEC function). Much to my sur-
  776.           prise, I found that much BBS system software is not written
  777.           properly. Starting at version V1.10, I included the
  778.           "BAD_BBS" routines to help overcome some of the loading
  779.           problems that these BBS systems have. In some cases this
  780.           work-around was successful and in others it was not. In
  781.           version V1.13, I included some tests that verify whether or
  782.           not JMODEM has been loaded properly. Instead of crashing the
  783.           system, JMODEM now prints an error message and exits. These
  784.           error messages can help you find out what the problem is
  785.           and, hopefully, obtain a solution.
  786.  
  787.           Presently, when JMODEM is loaded one of the first things it
  788.           does is make a DOS call to give up all memory except that
  789.           which contains the code. If DOS returns an error, it means
  790.           that JMODEM was not loaded properly and therefore doesn't
  791.           own any memory to give up! If an error message appears
  792.           telling you that JMODEM doesn't own any memory, you must
  793.           contact the writer of your BBS system software to obtain a
  794.           version that has this bug fixed. There will be no way to
  795.           execute JMODEM in this kind of environment without risking
  796.           serious system crashes.
  797.  
  798.           The next thing JMODEM does is make a DOS call, requesting
  799.           64k (-1) bytes of memory for its necessary buffer space. If
  800.           this DOS call fails, a message is printed stating that there
  801.           is not enough memory available for JMODEM. In this case, you
  802.           simply reconfigure your BBS software to provide enough mem-
  803.           ory for the external protocol. On some BBS systems, this is
  804.           done by defining "block-size". Generally, you just specify
  805.           the largest number that your BBS software will accept and
  806.           therefore force the BBS system software to allocate a large
  807.           block of memory for the external protocol.
  808.  
  809.           Although the code size of JMODEM is small (around 4k), it
  810.           requires just as much memory as other external protocols.
  811.           The memory is used for three major buffers:
  812.                 (1) Data buffer  8198 bytes
  813.                 (2) Encode/decode buffer 32,767 bytes
  814.                 (3) Interrupt buffer 20,000 bytes
  815.  
  816.           These buffers are put in a separate segment so a wild bit-
  817.           stream input cannot cause a system crash. The index used for
  818.           addressing memory in the interrupt buffer simply wraps
  819.           around past 64k, back to zero. Of course you get data errors
  820.           when this happens, but no crash, and if the incoming bit-
  821.           stream ends before a time-out, the error is recoverable.
  822.  
  823.  
  824.  
  825.  
  826.                                      - 14 -
  827.                                               JMODEM Protocol  Page 15
  828.  
  829.           When satellite links lose lock, the result is usually a 20
  830.           to 30 second burst of noise (random bit-stream). At 9600
  831.           baud, you can easily overflow a buffer if it is not large
  832.           enough or is not allowed to wrap. Alternative methods are to
  833.           limit the size of the buffer and check the limit every time
  834.           a byte is put in the buffer. JMODEM doesn't do this for two
  835.           reasons. The first is the increased software overhead (the
  836.           check must be made for every byte in the interrupt service
  837.           routine) and the second is that you may be waiting for an
  838.           ACK. JMODEM always preserves the last byte in the buffer so
  839.           that, even with a noisy reverse-channel, the ACK/NAK can be
  840.           extracted.
  841.  
  842.           These are the error messages and what they mean.
  843.  
  844.           JMODEM error message:
  845.           Specified file "" not found
  846.  
  847.           This means that no file name was passed to JMODEM on the
  848.           command line during a download.
  849.  
  850.           JMODEM error message:
  851.           Specified file "\D:PATH\FILENAME.TYP" not found
  852.  
  853.           This means that an incorrect file name was passed to JMODEM
  854.           on the command line during a download.
  855.  
  856.           JMODEM error message:
  857.           Specified file "" Can't be created.
  858.  
  859.           This means that no file name was passed to JMODEM on the
  860.           command line during an upload.
  861.  
  862.           JMODEM error message:
  863.           Specified file "\D:PATH\FILENAME.TYP" Can't be created.
  864.  
  865.           This means that an incorrect file name was passed to JMODEM
  866.           on the command line during an upload or:
  867.  
  868.                 o       The path doesn't exist
  869.                 o       The drive doesn't exist
  870.                 o       Not enough file handles
  871.                         Put FILES=40 in CONFIG.SYS and reboot
  872.                 o       Attempt to write to a network drive
  873.                         If you are not networked, do NOT install SHARE
  874.  
  875.           JMODEM error message:
  876.           File transfer aborted!
  877.  
  878.           This is a normal abort. If the user didn't abort then the
  879.           active communications adapter port is not being passed to
  880.           JMODEM correctly.
  881.  
  882.  
  883.  
  884.  
  885.                                      - 15 -
  886.                                               JMODEM Protocol  Page 16
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.                                      - 16 -
  945.                                               JMODEM Protocol  Page 17
  946.  
  947.           JMODEM error message:
  948.           Modem carrier failed.
  949.  
  950.           Modem either was not online or the user hung up during
  951.           protocol execution.
  952.  
  953.           JMODEM error message:
  954.           Can't execute, no free RAM!
  955.  
  956.           A poorly-written BBS system attempted to load the program as
  957.           a subroutine and execute it. Contact the BBS software
  958.           writer.
  959.  
  960.           JMODEM error message:
  961.           This program was already loaded over resident code.
  962.           The system will probably crash!
  963.  
  964.           A poorly-written BBS system just loaded JMODEM over its own
  965.           code!
  966.  
  967.           JMODEM error message: Can't create file VIRTUAL.MEM
  968.           JMODEM error message: Can't write file VIRTUAL.MEM
  969.           JMODEM error message: Can't close file VIRTUAL.MEM
  970.           JMODEM error message: Can't open file VIRTUAL.MEM
  971.           JMODEM error message: Can't delete file VIRTUAL.MEM
  972.  
  973.           When compiled with the BAD_BBS system conditional set to
  974.           "TRUE", JMODEM was unable to do the required file I/O be-
  975.           cause something was screwed up by the BBS software or there
  976.           were not enough file handles available. Enter FILES=40 in
  977.           CONFIG.SYS and reboot. This can also happen if SHARE is
  978.           installed and no network exists. Do NOT use SHARE if you are
  979.           not networked!
  980.  
  981.           JMODEM error message:
  982.           DOS reports that JMODEM was improperly loaded and does not
  983.           own the memory it is using!
  984.  
  985.           The BBS system software is either improperly configured or
  986.           improperly written for external protocols. Contact the
  987.           writer of the BBS system software.
  988.  
  989.           JMODEM error message:
  990.           Not enough free memory for JMODEM to use!
  991.  
  992.           The BBS system software is not properly configured to give
  993.           JMODEM the memory it requires to execute. Check the BBS
  994.           system software documentation and reconfigure.
  995.  
  996.           If you have problems using JMODEM with your system, you can
  997.           call the PROGRAM EXCHANGE and leave a message You can also
  998.           test your communications program's external file-transfer
  999.  
  1000.  
  1001.  
  1002.  
  1003.                                      - 17 -
  1004.                                               JMODEM Protocol  Page 18
  1005.  
  1006.           protocols by transferring files (hopefully uploading) to the
  1007.           PROGRAM EXCHANGE. Currently there are hundreds of boards
  1008.           that are using this protocol and the number is growing every
  1009.           day. Most problems encountered are found to be caused by
  1010.           incorrect file names being sent to JMODEM (the wrong "%"
  1011.           parameters). A simple batch file to test these parameters
  1012.           will go a long way towards solving the problems.
  1013.  
  1014.                                 Richard B. Johnson
  1015.                                 PROGRAM EXCHANGE
  1016.                                 (508) 922-3166
  1017.                                 Beverly, Massachusetts
  1018.  
  1019.  
  1020.           - Finis -
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.                                      - 18 -
  1063.